feat(cli): print, draw and check the plan an extension compiles - #49

Summary

describePlan (#46) made the plan readable as data. This makes it reachable from a shell:

npx vscode-ext-kit plan ./out/extension.js                    # the plan as JSON
npx vscode-ext-kit plan ./out/extension.js --format mermaid   # modules, services and their edges
npx vscode-ext-kit plan ./out/extension.js --format dot       # the same, for Graphviz
npx vscode-ext-kit plan ./out/extension.js --check            # exit 1 with every problem preflight found

The entry module is the extension's own — ESM source or the CommonJS bundle it ships — and the plan is whatever defineExtension compiled when that module was evaluated. Export the result as app, or name the export with --export.

How it evaluates an extension outside VS Code

vscode exists only inside an extension host, so the tool evaluates the entry with a stand-in: a proxy that answers every property and does nothing. That is enough because nothing in this package touches VS Code before activate — defineExtension compiles the plan and stops — and an extension's module-scope code is held to the same rule by the framework's design. ESM imports are redirected by a module-resolution hook; CommonJS require('vscode'), which is what a bundled extension does, by Node's CommonJS resolver. Both paths land on the same stand-in, so a production bundle reads the same way an unbundled entry does.

The consequence for authors is the one the framework already asks for: keep VS Code reads inside activate or a handler. Module-scope code that reads a VS Code value gets a proxy instead of a crash, and the failure surfaces where it belongs — in a real host.

Output

• json — exactly what describePlan returns; deterministic, so it can be committed and diffed.
• mermaid / dot — one subgraph per module holding its services (with lifetime), commands, hosted services, watchers and views; dependency edges between them; framework services something depends on in a subgraph of their own, so no edge points at nothing.
• --check — a one-line summary and exit 0, or the list of preflight problems (code, subject, module, message) on stderr and exit 1. Exit 2 is a usage or load error.

Where it lives, and how it is checked

The tool is bin/vscode-ext-kit.mjs, outside src/, which may not touch Node. verify:package now runs it from the installed tarball against a plan written in the throwaway consumer project, so the one place the stand-in meets a real install is exercised on every run. A test suite drives it as a child process across every format and exit code.

It was also run against a published extension's real CommonJS bundle, unmodified, and read the plan out of it.

Compatibility

Additive: a bin entry, bin/ in files. No runtime code changes.

🤖 Generated with Claude Code